Update jdbc doc with connection wrapping disclaimer #14884
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
laurit
reviewed
Oct 6, 2025
docs/instrumentation-list.yaml
Outdated
| - name: jdbc | ||
| description: | | ||
| The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs. | ||
| The instrumentation unwraps pooled connections to cache database metadata. If your connection pool doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, causing higher CPU usage. |
There was a problem hiding this comment.
I think this will require more careful wording. CPU usage isn' the real issue. The problem is that calling getMetaData may result in querying database (what this method does depends on the database driver, also the driver may cache the results). I'd suggests you to rephrase with emphasis on that instrumentation requires that connections can be unwrapped and that inability to unwrap may cause degraded performance or have increased overhead with some jdbc drivers. Below you also mention that unwrapping is needed for attributing work to correct connection. There was recently an issue with shardingsphere where we showed the wrong database for some queries.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #8303